home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 98 / Skunkware 98.iso / src / net / omniORB-2.5.0-src.tar.gz / omniORB-2.5.0-src.tar / omniORB_2.5.0 / README.win32 < prev   
Text File  |  1998-02-05  |  13KB  |  345 lines
  1.                         omniORB2 on Win32 platforms.
  2.                         ============================
  3.  
  4. This file contains information on installing, building, and using omniORB2
  5. on Win32 (Windows NT and Windows '95) platforms.
  6.  
  7. If you are upgrading from 2.2.0, do not miss the important information about
  8. omniNames at the end of this note.
  9.  
  10. OmniORB 2.5.0 has been tested with the following software configuration:
  11.  
  12. - Operating System  : Windows NT 4.0
  13. - Architecture      : x86
  14. - Compiler          : Visual C++ 4.2, Visual C++ 5.0
  15.  
  16. The omniORB2 binaries, when compiled using VC++ 5.0 on Windows NT, will 
  17. execute on Windows '95 machines and vice-versa.
  18.  
  19. omniORB2 hasn't been built or tested on Alpha Windows NT, but this should
  20. be possible. (Please e-mail omniorb@orl.co.uk if you do this).
  21.  
  22.  
  23. Roadmap
  24. =======
  25.  
  26. When the omniORB2 distribution is unpacked, the following are created:
  27.  
  28. <Top-Level Directory>\                     : Directory where distribution was 
  29.                                              unpacked
  30.  
  31. <Top-Level Directory>\doc\                 : omniORB2 Documentation
  32.  
  33. <Top-Level Directory>\include\             : Include files
  34. <Top-Level Directory>\include\omniORB2\    : Include files for ORB run-time 
  35.                                              library
  36. <Top-Level Directory>\include\omnithread.h : Main omnithread include file
  37. <Top-Level Directory>\include\omnithread\  : Include files for thread library
  38.  
  39. <Top-Level Directory>\src\                 : Source files
  40. <Top-Level Directory>\src\lib\omniORB2\    : Source files for ORB run-time 
  41.                                              library
  42. <Top-Level Directory>\src\lib\omnithread\  : Source files for thread library
  43. <Top-Level Directory>\src\tool\omniidl2\   : Source files for IDL Compiler
  44. <Top-Level Directory>\src\appl\omniNames\  : Source files for COS Naming 
  45.                                              Service
  46. <Top-Level Directory>\src\appl\utils\      : Source files for utilities
  47. <Top-Level Directory>\src\examples\        : Source for example programs
  48.  
  49.  
  50. Installation
  51. ============
  52.  
  53. If you downloaded the Win32 binary distribution of omniORB2, ready-built
  54. binaries are provided. You are ready to go.
  55.  
  56. The executables and DLLs are in <Top-Level Directory>\bin\x86_win32.
  57. The libraries are in            <Top-Level Directory>\lib\x86_win32.
  58.  
  59. You *should* set up your PATH environment to include 
  60.    <Top-Level Directory>\bin\x86_win32
  61. otherwise the DLLs will not be picked up when omniORB programs are run.
  62.  
  63. If you have the source-only distribution, you will need to build omniORB2. 
  64. Please read the  "Building omniORB2 from the source files" section, below. 
  65. (If you want the  Win32 binary distribution, but don't have it, you can 
  66. download it from the ORL web site at 
  67. http://www.orl.co.uk/omniORB/omniORB.html).
  68.  
  69. Configure the naming service
  70. =============================
  71.  
  72.   If you are upgrading from 2.2.0, please read the important information about
  73.   omniNames at the end of this note.
  74.  
  75.   You have to configure the omniORB2 runtime and the naming service,
  76.   consult the user guides in ./doc for details. For a quick start, follow
  77.   these steps:
  78.  
  79.     o Make sure that <Top-Level Directory>\bin\x86_win32 is in your
  80.       PATH environment.
  81.  
  82.     o Set the environment variable OMNINAMES_LOGDIR to a directory where
  83.       the naming service omniNames can store its data. For example:
  84.           set OMNINAMES_LOGDIR=C:\OMNINAMES
  85.  
  86.     o Start omniNames. The binary is in <Install Location>\bin\win32_x86. 
  87.       For example:
  88.          omniNames -start 12345
  89.       Notice that you have to give as a parameter to the option -start
  90.       the TCP/IP port number omniNames will use to receive IIOP requests.
  91.  
  92.     o omniNames writes the stringified object reference for its root context 
  93.       on standard error.
  94.       Copy the IOR. (including the IOR: prefix).
  95.  
  96.     o Start the tool REGEDT32.EXE (on NT) or REGEDIT.EXE (on Windows '95). 
  97.       Select the key  HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0 (or create
  98.       it if it doesn't exist). Add a string value (known as a REG_SZ data type
  99.       when using REGEDT32) called NAMESERVICE  , and paste the IOR in to the 
  100.       value field associated with it.
  101.  
  102.  
  103. Compiling the examples with nmake
  104. =================================
  105.  
  106. Once the installation is completed. You can try compiling and running the
  107. examples in <Top-Level Directory>\src\examples.
  108.  
  109. Just do the following:
  110.  
  111.   cd <Top-Level Directory>\src\examples
  112.   nmake /f dir.mak
  113.  
  114. Have a look at the dir.mak file in <Top-Level Directory>\src\examples, it
  115. should give you some idea about the compiler flags and libraries to compile
  116. and link omniORB2 programs.
  117.  
  118. Building Projects using omniORB2
  119. ================================
  120.  
  121. Before building anything (or running the examples), you should refer to the 
  122. omniORB2 documentation. In particular, you must add the (stringified) object 
  123. reference of the naming service to the registry (in the (string) value 
  124. NAMESERVICE, under the key HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0). 
  125. You should use the tool REGEDT32.EXE on Windows NT, or REGEDIT.EXE on 
  126. Windows '95. (See above for quickstart instructions on starting the Naming
  127. Service).
  128.  
  129. Note that the instructions below are for Microsoft Visual C++ 4.2, using 
  130. Microsoft Developer Studio. If you are using Microsoft Visual C++ 5.0, the 
  131. setup will be slightly different. The instructions are for using the DLL
  132. versions of omniORB2 and omnithread.
  133.  
  134. a) Add the stub (SK.cpp) files generated by the IDL compiler to the project 
  135.    (Insert->"Files into Project")
  136.  
  137. b) Set up the search paths for include and library files: 
  138.  
  139.    1. Under Tools->Options, select the Directories tab.
  140.    2. In the "Show directories for" box, select "Include files".
  141.    3. Add the directory where you installed the omniORB2 include files to the 
  142.        list (this is <Top-Level Directory>\include).
  143.    4. In the "Show directories for" box, select "Library files".
  144.    5. Add the directory where you installed the omniORB2 library files to the
  145.        list (this is <Top-Level Directory\lib\x86_win32).
  146.     
  147. c) Set up macros and libraries:
  148.  
  149.     1. Under Build->Settings, select the "C/C++" tab.
  150.     2. In the "Category" box, select "C++ Language". Tick the 
  151.         "Enable exception handling" box.
  152.     3. In the "Category" box, select "Code Generation". In the 
  153.         "Use run-time library" box, select "Multithreaded DLL".
  154.     4. **This is an import step.** 
  155.        In the "Category" box, select "Preprocessor". In the
  156.         "Preprocessor" box, add the macros __WIN32__,__x86__.
  157.        If this is NT 4.0, add the macros __NT__ and __OSVERSION__=4 as well.
  158.     
  159.     5. Select the "Link" tab.
  160.     6. In the "Category" box, select "Input". In the "Object/library modules"
  161.        box, add the following libraries: wsock32.lib, advapi32.lib, 
  162.        omniORB24_rt.lib, omnithread2_rt.lib
  163.  
  164.    If you are building a debug executable, the debug version of the libraries:
  165.    omniORB24_rtd.lib and omnithread2_rtd.lib should be used.
  166.  
  167. d) Your project is now set up, and you can build it.
  168.  
  169.  
  170. If you want to use the static versions of omniORB2 and omnithread, you must
  171. add the macro _WINSTATIC (see step (c) 4, above), and replace the libraries
  172. omniORB24_rt.lib and omnithread2_rt.lib with omniORB2.lib and omnithread.lib 
  173. (see step (c) 6, above).
  174.  
  175.  
  176. Important Change to omniNames for users upgrading from version 2.2.0
  177. ====================================================================
  178.  
  179. Since release 2.4.0, the naming service has used the prefix pragma "omg.org" in
  180. its IDL.
  181.  
  182. Unfortunately, this is not compatible on-the-wire with clients that are
  183. linked with the old library, i.e. any programs linked before version 2.4.0
  184. was released.
  185.  
  186. The implications of this change are as follows:
  187.  
  188. a) omniNames built in this release *CANNOT* read the data file of the version
  189.    2.2.0 omniNames. A new instance must be started from scratch. If you start
  190.    omniNames and tell it to use the old data file, it will certainly crash.
  191.  
  192.    Possible migration path:
  193.      At, we are running the old and the new omniNames in parallel.
  194.      The new instance is setup to run on a different port. Also the
  195.      new tree is built to read by default a different configuration file:
  196.      (/project/omni/var/omniORB_NEW.cfg instead of 
  197.      /project/omni/var/omniORB.cfg) so that a client will pick up the
  198.      IOR of the old or the new omniNames depending on whether it is compiled
  199.      with the old or the new library. When all our services have been
  200.      recompiled, the old omniNames will be withdrawn.
  201.  
  202.  
  203. b) If you want to continue to use the old omniNames, you can undo this
  204.    change with the following steps:
  205.      1. Edit <Top directory>\src\lib\omniORB2\Naming.idl and remove the 
  206.         #pragma prefix "omg.org" line.
  207.      2. Do the same to <Top directory>\idl\Naming.idl.
  208.      3. Remove <Top directory>\include\omniORB2\Naming.hh.
  209.      4. Rebuild everything. You should do a make veryclean at the
  210.         top of <Top directory>\src to make sure that the naming service stubs 
  211.         are regenerated.
  212.  
  213.  
  214.  
  215. Known Problems
  216. ==============
  217.  
  218. When compiling the stub files generated by omniidl2, you may come across
  219. some bugs in Microsoft Visual C++ 4.2 (not fixed in Microsoft Visual C++
  220. 5.0). The bugs are to do with the handling of nested classes. You may
  221. come across these bugs if you use modules in your IDL files, and in certain
  222. other circumstances.
  223.  
  224. Unlike 2.2.0, this release generates stub code that works around most of
  225. the MS VC++ bugs. However, it is not possible to avoid the bugs in all
  226. cases. In particular, the following sample IDL will fail to compile:
  227.  
  228. // IDL
  229.  
  230. module A {
  231.   struct B {
  232.     long x;
  233.   };
  234.   enum C { C_1, C_2 };
  235.   module D {
  236.      struct B {
  237.        float y;
  238.      };
  239.      // The stub for struct E would fail to compile
  240.      struct E {
  241.        A::B e1;
  242.        B    e2;
  243.   };
  244. };
  245.  
  246.  
  247.  
  248. Building omniORB2 from the source files
  249. =======================================
  250.  
  251.  OmniORB2 should be compiled using Visual C++ 4.2 or Visual C++ 5.0.
  252.  
  253.  
  254.  A. Pre-requisites
  255.     --------------
  256.  
  257.     Starting from this release, the omniORB2 source tree requires the 
  258.     gnu-win32 utilities from Cygnus Solutions to build.
  259.  
  260.     The full distribution is freely available at:
  261.  
  262.        ftp://ftp.cygnus.com/pub/gnu-win32/latest
  263.  
  264.     or in UK
  265.  
  266.        ftp://src.doc.ic.ac.uk/public/gnu/cygnus/gnu-win32/latest
  267.  
  268.  
  269.     The toolkit is big and you don't need all of it to compile
  270.     omniORB2. Alternatively, you can download a cutdown version from:
  271.  
  272.        ftp://ftp.orl.co.uk/pub/omniORB/gnu-win32-lite.zip
  273.  
  274.     The utilities in this version are all you need to build omniORB2.
  275.  
  276.     Assume that you have downloaded the toolkit and have unpacked/installed
  277.     it in some sensible subdirectory, say C:\gnuwin32, you then have to go
  278.     through the following checklist:
  279.  
  280.       1. In a command prompt window, make sure that you have the environment
  281.          variables and path setup properly to use MS Visual C++ (4.2/5.0).
  282.  
  283.          For instance, I have MS VC++ installed in C:\Program Files\DevStudio.
  284.          The following environment variables should be set to:
  285.  
  286.          LIB=C:\Progra~1\DevStudio\VC\lib
  287.         INCLUDE=C:\Progra~1\DevStudio\VC\include
  288.         Path=<otherpaths>;C:\Progra~1\DevStudio\VC\bin;C:\Progra~1\DevStudio\SharedIDE\bin;<otherpaths>
  289.  
  290.       2. If you have unpacked gnu-win32-lite.zip in C:\gnuwin32, add
  291.          C:\gnuwin32\bin to your Path environment variable. 
  292.  
  293.         Warning: If you have installed posix utilities from the Windows 
  294.             resource kits, make sure that C:\gnuwin32 is searched before the 
  295.             directory containing these utilities.
  296.  
  297.        If you have installed the full gnu-win32 toolkit, just follow its
  298.        installation instructions and you can skip 3.
  299.  
  300.       3. Now you have to run a small script *once* to setup in your registry 
  301.          the necessary 'mount' points. Basically, it tells the gnu-win32 
  302.          runtime how to translate a path such as /bin/sh to the real path 
  303.          name Win32  (e.g. C:\gnuwin32\bin\sh.exe) understands.
  304.  
  305.          Just execute this command in a command prompt window:
  306.   
  307.             C:\gnuwin32\bin\checkmounts C:\gnuwin32
  308.  
  309.         If all goes well, this is what you see:
  310.  
  311.             C:\> C:\gnuwin32\bin\checkmounts C:\gnuwin32
  312.             no /bin/sh.exe, mounting c:\gnuwin32\bin as /bin
  313.             Completed successfully.
  314.  
  315.       4. Now you are ready. You can now build the distribution by following 
  316.          the instructions below.
  317.  
  318.  
  319.   B. Choose the right platform configuration file
  320.      --------------------------------------------
  321.  
  322.       Edit <top>\config\config.mk to select one of the following:
  323.  
  324.      platform = x86_nt_3.5
  325.      platform = x86_nt_4.0
  326.      platform = x86_win95
  327.  
  328.  
  329.   C. Building and installing
  330.      --------------------------
  331.  
  332.      Go into the directory <top>\src and type 'make export'. If all
  333.      goes well:
  334.         1. The executables and DLLs will be installed into
  335.                <top>\bin\x86_win32\
  336.         2. The libraries will be installed into
  337.                <top>\lib\x86_win32\
  338.  
  339.  
  340. Mailing List
  341. ============
  342.  
  343. There is a mailing list for discussing the use and development of
  344. omniORB2. See README.FIRST for details on subscribing.
  345.